Page-Level Testing with Cypress & cypress-axe

In the previous section on Cypress Component Testing, we looked at the cypress-axe extension to check for accessibility issues at the component level.

As mentioned, cypress-axe is more useful when used to test at the page level than at the component level.

However, the types of issues that it identifies should be caught earlier in the process.

That said, the goal of this lesson is to become more familiar with the Cypress UI and get used to thinking about testing on the page level.

Find Accessibility Issues on the Page-Level with cypress-axe

Let’s write a test that uses cypress-axe to ensure we don’t have any accessibility issues on the Home page.

As we saw in the lessons on Cypress Component Testing, we’ll tell Cypress to inject axe in the beforeEach block.

We’ll write a new it block with a description that we should not have any accessibility violations on load.

Like we did before, we’ll call cy.checkA11y() but this time we won’t pass any options to it since we want it to run all of the axe-core rules at the page level.

The test looks like this:

describe('HomePage', () => {
    beforeEach(() => {
        cy.visit('http://0.0.0.0:1234/')
        
        cy.injectAxe()
    })
    it('should have no accessibility violations', () => {
        cy.checkA11y()
    })
})

describe('HomePage', () => {
    beforeEach(() => {
        cy.visit('http://0.0.0.0:1234/')
        
        cy.injectAxe()
    })
    it('should have no accessibility violations', () => {
        cy.checkA11y()
    })
})

Running Cypress, the UI will show us the test results and the issues that are present on the page.

There are four issues that Cypress has identified:

• A missing button name.
• Missing image alt descriptions.
• A landmark issue.
• A couple of region issues.

It is important that these issues get resolved, as they negatively impact the experience for screen reader users.

🛠 Challenge: Fix the Issues Identified by Cypress

Cypress has identified several issues that can be fixed with some refactoring of the CampSpots app markup. Work through the issues until the test passes successfully.

Selecting an item in the sidebar and the DevTools Console will display additional information from Cypress about the issues it has identified.

As seen in the screenshot below this including specific Nodes, rule tags such as WCAG success criteria or best practices, and a link to learn more about the identified issue.

🛠 Solution: Fixing Identified Issues

Updating Alt Descriptions on the Homepage

Using the Nodes output from the console can help locate where in the codebase the images are missing alt attributes. We can search by filename or for the classname from the target CSS selector.

Image alt descriptions can be quite subjective.

The “Tents at Sunset” image on the homepage contributes content to the page but lacks an alt attribute. For this one, add a description of the photo.

There’s also a missing alt attribute on the CampSpots logo image. This we can treat a bit differently.

An alt description of the image being “tent image” probably isn’t the most useful description to include. Because the image is wrapped in a link along with a text span that says the name of the site, a screen reader would say something along the lines of “Link: tent image CampSpots”.

However, if we don’t add an alt attribute, the screen reader will read out aloud the cryptic, cached filename from the image’s src.

For the logo image in header.js, using an empty string for the alt attribute will work fine since it has redundant content to its span sibling. This way the screen reader will announce “Link: CampSpots” for the wrapping link element and ignore that there’s even an image there.

Refactoring the Header & Footer to use Landmarks

One of the issues that Cypress found was a missing image alt attribute in the footer, which currently has its markup inside of App.js.

Adding an alt description of “CampSpots” to the footer image is a quick fix.

While we’re working with the footer, another thing Cypress found was that the current markup doesn’t use landmark elements. Landmarks are a best practice for screen reader navigation and are worth including on pages.

To fix this, we can swap out the footer’s <div> with the semantic <footer> landmark element.

The Footer markup now looks like this— feel free to extract it to its own component!

// inside of App.js
<footer id="footer">
	<div className="layout">
		<div id="footer-logo">
			<img src={imgFooterLogo} alt="CampSpots" />
		</div>
	</div>
</footer>

// inside of App.js
<footer id="footer">
	<div className="layout">
		<div id="footer-logo">
			<img src={imgFooterLogo} alt="CampSpots" />
		</div>
	</div>
</footer>

We also need to fix the Header component to use the <header> landmark.

Inside of components/header.js swap out the <div> with <header>.

Finally, we add our only main in our App.js by switching the <div> to <main>. Leaving us with three top level landmarks.

Add a Button Name to the IconButton Component

There’s one error left in Cypress and it has to do with the missing name for the IconButton component.

As it happens, we had fixed this issue back in the section on Unit Testing with Jest. But we didn’t update the actual usage in the application!

Inside of components/search-form.js, add a name prop with a value of “Submit” to the IconButton component:

<IconButton name="Search" onClick={() => console.log('Submit my stuff!')} />

<IconButton name="Search" onClick={() => console.log('Submit my stuff!')} />

A Note About the H1 Region Error

CampSpots has an H1 up above the Header component which has H2s for all of the MegaNav buttons. We built this heading structure with a React Portal in the Semantics & ARIA Workshop.

We are seeing this error in Cypress because the H1 is not inside of a landmark, but in my opinion having a proper heading structure is more important.

Screen reader users are more likely to navigate a page by heading structure than they are by landmarks.

Ideally the H1 should be part of the header landmark, but it would require some rearchitecting to make it work.

I don’t agree with this being a violation, but on a team in the real world you shouldn’t build a bad habit by training them to overlook accessibility violations because “it’s okay” in certain situations.

Exclude an Element from cypress-axe

To exclude the header portal from being tested by cypress-axe, we can add a config object to the cy.checkA11y() call.

The object takes a key called exclude whose value is an array of selectors to ignore. In this case, we can use the target element from the console output that points to the portal.

Here’s what our test looks like now:

it('should have no accessibility violations', () => {
        cy.checkA11y({
            exclude: ['div#portal-root']
        })
    })

it('should have no accessibility violations', () => {
        cy.checkA11y({
            exclude: ['div#portal-root']
        })
    })

With all the issues from cypress-axe addressed, we have a passing HomePage test suite!